Each <DataSource> node has the following format:

<DataSource ID="id" View="view or table name" Lookup="identifier" FieldName="field" />

where:

• ID – a unique identifier for the data source. You use this to identify the data you want to use in the endpoint and body.

• View – the name of the view or table in the MyID database that contains the data you want to use.

• Lookup – the identifier used to look up the appropriate record in the table or view. You can use the following values:

  • DeviceID – the ID of the device that is the subject of the notification.

  • PersonID – the ID of the person who is the subject of the notification.

  • JobID – the ID of the job of the operation that is being carried out.

• FieldName – optionally, if it is not the same as the Lookup value, the name of the field in the view or table to compare against the identifier.

For example:

<DataSources>
  <DataSource ID="People" View="vPeopleUserAccounts" Lookup="PersonID" />
  <DataSource ID="Devices" View="vDevices" Lookup="DeviceID" />
</DataSources>

This creates two data sources:

• A data source called People that contains the data from the vPeopleUserAccounts view in the MyID database. The ID of the person who is the subject of the notification is used to match against the PersonID in the view.

• A data source called Devices that contains the data from the vDevices view in the MyID database. The ID of the device that is the subject of the notification is used to match against the DeviceID field in the view.

You can now access any field in the vPeopleUserAccounts view for the person, or the vDevices view for that device; for example, to include the device GUID in the endpoint:

<Endpoint Verb="POST" URL="/devices/{Devices.ObjectID}/deviceCancelled" />

or, to include the person's email address in the body payload:

<Source Field="Email" Retrieval="People" />

14.3.2.1 Where clauses

Optionally, you can add one or more <Where> nodes inside the <DataSource> node. This node has the following format:

<Where FieldName="fieldname" FieldValue="fieldvalue" Operation="operation" Conjunction="[and|or]" />

where:

• FieldName – the name of a field in the view or table.

• FieldValue – the value to compare against the content of this field.

• Operation – the comparison operation. You can use the following:

  =	equal to – the default when a single field value is specified
  !=	not equal to
  lt	less than
  le	less than or equal to
  gt	greater than
  ge	greater than or equal to
  like	like
  isnull	value is null
  notnull	value is not null
  IN	value is one of the listed values – the default when multiple values are specified

• Conjunction – optionally, the conjunction where you have multiple <where> nodes. You can use the following:

  and

  or

For example:

<DataSource ID="PivAuthCert" View="vCertInstances" Lookup="DeviceID">
  <Where>
    <FieldName>ContainerName</FieldName>
    <FieldValue>5FC105</FieldValue>
    <Operation>=</Operation>
  </Where>
</DataSource>

This returns the details from the vCertInstances view for the device that is the subject of the notification; as there are multiple certificates for a single device, the <where> node restricts the returned data to the certificate where the container name matches the name for the PIV Authentication certificate.

14.3.3 Endpoint

The <Endpoint> node specifies the REST web service endpoint to which MyID sends the notification. The format is:

<Endpoint Verb="verb" URL="url"/>

where:

• Verb – the HTTP verb used to call the REST web service. You can use the following:

  • POST (this is the default)

  • PUT

  • DELETE

  • PATCH

• URL – the endpoint on the server.

  The URL to which MyID sends the notification is constructed from the API Location field in the external system (see section 14.1, Configuring an external system for REST notifications) and the URL you provide in the mapping file.

  You can include substitutions from your data sources in this endpoint; for example, you may want to include the device GUID. Use the following format:

  {DataSource.FieldName}

  For example:

  {Devices.ObjectID}

For example:

<Endpoint Verb="POST" URL="/devices/{Devices.ObjectID}/deviceCancelled" />

If the API Location field in the external system is:

https://myserver/Notify

and the device GUID (as obtained from the ObjectID field in the Devices data source, which refers to the vDevices view in the database) is:

79036d80-8322-404f-b146-f37af6b016b4

then MyID sends a POST request to:

https://myserver/Notify/devices/79036d80-8322-404f-b146-f37af6b016b4/deviceCancelled

14.3.4 Body

The <Body> node specifies the data that is sent to the REST web service.

Within the <Body> node, you can include one or more <Property> nodes. Each <Property> node has a JPath attribute that specifies the location in the JSON output where the value is to be included, and a <Source> node that specifies the data to include in the JSON output for the specified JPath.

The format is:

<Property JPath="path">
  <Source
    Retrieval="datasource" 
    Field="fieldname" 
    EncodingFormat="format" 
    DataType="type" 
    Default="staticvalue" />
</Property>

where:

• JPath – the path in the JSON output to create.

  For example, device.id creates a top-level element called device and within that an element called id.

• Retrieval – the name of the data source from which you want to obtain the data.

• Field – the name of the field in the data source you want to include.

• EncodingFormat – if you are retrieving Boolean or date information from the database, specify one of the following:

  • Boolean – the value is output as true or false.

  • Date – the value is output in ISO8601 date time format: yyyy-MM-ddTHH:mm:ss.000Z

• DataType – if you are retrieving image, base64, or GUID data from the database, specify one of the following:

  • Image – the image is stored as binary object data in the database.

    Note: You cannot access image data when the data is stored as a file; you can access only image data that is stored as binary object data in the database.

  • HexedB64Certificate – the retrieved data is in hexed base64 format. The data is converted to base64 format and any carriage return or line feed characters are removed before they are written to the JSON body.

  • Guid – when retrieving a GUID from the database (for example, the ObjectID for a device) it is enclosed in braces {} – you cannot include these in a JSON file. Specify a DataType of Guid to strip the braces from the GUID before writing it to the JSON body.

• Default – a static value to use if the retrieval from the database does not produce a value. Alternatively, you can use the Default attribute instead of the Retrieval and Field attributes to provide a static value.

  If you do not provide a Default value, and the retrieval from the database does not produce a value, the path specified in the JPath is not included in the JSON output.

For example:

<Property JPath="device.validity.enabled">
  <Source EncodingFormat="Boolean" Field="Enabled" Retrieval="Devices" />
</Property>

This obtains the value for Enabled field in the Devices data source, which refers to the vDevices view in the database; this value is 0 or 1 in the database, but the EncodingFormat tells MyID to output it as true or false to the appropriate place in the JSON output; for example:

{ 
  "device": {
    "validity": {
      "enabled": true
    },
  }
}

14.3.4.1 Additional processing

Optionally, you can add a <Processor> node inside the <Source> node to carry out additional processing on the value obtained from the database. This node has the following format:

<Processor Type="type" P1="Param1" P2="Param2" />

where:

• Type – currently, this must be:

  • substring – obtains a part of the string value.

• P1 – the first parameter. For substring, this is the start location (based on zero-based indexing).

• P2 – the second parameter. For substring, this is the number of characters. If you do not specify a number of characters, the value returned is from the start location to the end of the string.

For example:

<Property JPath="device.fascn">
  <Source Field="SN3" Retrieval="Devices">
    <Processor Type="substring" P1="14" P2="6"/>
  </Source>
</Property>

This obtains the value for the SN3 field in the Devices data source, which refers to the vDevices view in the database, then obtains a 6-character section of this value starting at position 14 (based on zero-based indexing).

If the SN3 value is:

0011 - 0000 - 250018 - 1 - 1 - 0000000001 1 1234 4 - 28

the output is:

{
    "device": {
        "fascn": "250018"
        },
    }
}